# -*- coding: utf-8 -*-
"""
Created on Tue Oct  4 18:38:49 2016
twsited源码
@author: zxj
"""

'''
Protocol对象用于实现协议的内容。也就是说一个具体的Twisted的Protocol的实现应该对应
一个具体网络实现协议。例如FTP、IMAP或者其他我们自己制定的协议,也就是通信规则？
每一个Protocols类实例都为一个具体的的连接提供协议解析。因此，我们的程序每当建立一条连接，
都需要一个协议实例，Protocol实例是存储协议状态与间断性（通过异步I/O方式以任意大小来
接收数据的）接受并累积数据的地方。
'''
class BaseProtocol:
    """
    This is the abstract superclass of all protocols.

    Some methods have helpful default implementations here so that they can
    easily be shared, but otherwise the direct subclasses of this class are more
    interesting, L{Protocol} and L{ProcessProtocol}.
    这是所有协议的抽象父类,一些方法已经有了很有用的默认实现
    """
    connected = 0
    transport = None

    def makeConnection(self, transport):
        '''
        
        该函数一个回调函数
        Twsited在调用它的时候会传入一个仅有的transport实例
        transport为协议要使用的连接
        '''
        """Make a connection to a transport and a server.
        
        This sets the 'transport' attribute of this Protocol, and calls the
        connectionMade() callback.
        设定协议的transport属性,然后回调connectionMade函数
        """
        self.connected = 1
        self.transport = transport
        self.connectionMade()

    def connectionMade(self):
        """Called when a connection is made.
        
        This may be considered the initializer of the protocol, because
        it is called when the connection is completed.  For clients,
        this is called once the connection to the server has been
        established; for servers, this is called after an accept() call
        stops blocking and a socket has been received.  If you need to
        send any greeting or initial message, do it here.
        当创建一个连接后，被调用。
        这被认为是协议的初始化，因为这个是在连接创建的时候被初始化
        对客户端而言，一旦连接到服务器将会被调用，对于服务器而言当一个accept调用停止阻塞并且
        一个socket被接收到的时候被调用
        如果需要发送一些问候或者初始化信息，写在这里
        """

class Protocol(BaseProtocol):
    """
    This is the base class for streaming connection-oriented protocols.

    If you are going to write a new connection-oriented protocol for Twisted,
    start here.  Any protocol implementation, either client or server, should
    be a subclass of this class.

    The API is quite simple.  Implement L{dataReceived} to handle both
    event-based and synchronous input; output can be sent through the
    'transport' attribute, which is to be an instance that implements
    L{twisted.internet.interfaces.ITransport}.  Override C{connectionLost} to be
    notified when the connection ends.

    Some subclasses exist already to help you write common types of protocols:
    see the L{twisted.protocols.basic} module for a few of them.
    该类是面向流的协议的基类，如果是写一个面向连接的协议，
    不管是客户端还是服务器都因该继承此类，该API十分简单，实现dataReceived处理基于事件的同步的输入，
    输出将通过transport属性。transport属性是实现了twisted.internet.interfaces.ITransport的实例
    """

    def logPrefix(self):
        """
        Return a prefix matching the class name, to identify log messages
        related to this protocol instance.
        返回一个匹配类型的前缀
        """
        return self.__class__.__name__


    def dataReceived(self, data):
        """Called whenever data is received.

        Use this method to translate to a higher-level message.  Usually, some
        callback will be made upon the receipt of each complete protocol
        message.
        使用此方法来转换一些高级别的信息，通常情况下，在收到每一个完整的协议消息后
        会有一些回调
        
        @param data: a string of indeterminate length.  Please keep in mind
            that you will probably need to buffer some data, as partial
            (or multiple) protocol messages may be received!  I recommend
            that unit tests for protocols call through to this method with
            differing chunk sizes, down to one byte at a time.
            不确定长度的字符串，务必记住你可能需要缓冲一些数据，
            因为部分或者多个协议可能会收到
        """

    def connectionLost(self, reason=connectionDone):
        """Called when the connection is shut down.

        Clear any circular references here, and any external references
        to this Protocol.  The connection has been closed.
        清楚此处的任何循环引用，以及该协议的任何外部引用

        @type reason: L{twisted.python.failure.Failure}
        """